Using the Grid List Box nodes

Use the Grid List Box nodes to create scrollable lists of items arranged in a grid.

Learn how to use the Grid List Box nodes by completing a tutorial. See Tutorial: Create a contacts list with a Grid List Box.

As you add items to a Grid List Box node, the Grid List Box node places them either in its first row or column:

To select an item in a Grid List Box node click or tap the item.

The Grid List Box node arranges its items based on what you set in the Layout Direction property:

When a Grid List Box node has focus use:

NOTE

Items in all list box nodes (Grid List Box nodes and Trajectory List Box 3D node) are not its child nodes, even though in Kanzi Studio it seems so when you add items to a list box. Because list box items are not child nodes of a list box, you cannot refer to these items from outside of a list box using paths or aliases. If you need to refer from a list box item to an object outside of a list box, use bindings and aliases. See Binding to properties outside of a Grid List Box node and Navigating to Page nodes from a Grid List Box node.

For a Grid List Box node you can:

Creating a Grid List Box node

To create a Grid List Box node:

  1. In the Project press Alt and right-click the node where you want to create a Grid List Box node and select either Grid List Box 3D, or Grid List Box 2D.
    Note that you can create a 3D node only inside 3D nodes, and 2D node only inside 2D nodes.
  2. In the Project add items to the Grid List Box node.
    Use a data source to add items to a List Box node. See Using a data source.
    For example, to create a contact list, add several nodes which represent the contacts in the list. See Using the List Box Item Container prefabs.
    As you add items, the Grid List Box node arranges them in a grid from the top-left towards the bottom-right corner of the Grid List Box node. See Setting how a Grid List Box node arranges its items.
    To browse the items in a Grid List Box node, in the Preview click and drag the items in the Grid List Box node.
  3. (Optional) If you cannot see the content you added to a Grid List Box node or the content does not fully fit, add and set the Cell Height and Cell Width properties.
    You set the area reserved for each element inside the list box. The cell size clips the items if the items do not fit in the cell.
  4. In the Project select the Grid List Box node and in the Properties set the Layout Height and Layout Width properties.
    You set the area in which the items in the Grid List Box node are visible. If all items in the Grid List Box node do not fit in the area, Kanzi clips those items which do not fit. The user can scroll the Grid List Box node to access all items.
  5. (Optional) In the Preview click to enter the Analyze mode, right-click , and select Debug objects.
    This way you visualize the borders of the Grid List Box node and the items in the Grid List Box node.

Setting how a Grid List Box node arranges its items

You can set the Grid List Box node so that it arranges its items either along the x or y axis.

To set how a Grid List Box arranges its items:

  1. Create a Grid List Box node and add items to it. See Creating a Grid List Box node.
  2. In the Properties set the Layout Direction property to either:

Bringing the selected item to the center of a Grid List Box

You can set a Grid List Box node to bring the item to the center of the list box area when a user clicks or taps that item.

To set items in a Grid List Box node to the center when the user selects them:

  1. Create a Grid List Box node and add items to it. See Creating a Grid List Box node.
  2. In the Properties add the Selection Behavior property and set it to Bring Center.
    You set the Grid List Box node to scroll an item to the center of the node area when the user selects that item. The Grid List Box node centers its items based on the value you set in the Layout Direction property. See Setting how a Grid List Box node arranges its items.
  3. In the Properties add and set:

    Use the Item Area Begin and Item Area End properties to:

Nesting Grid List Box nodes

You can nest Grid List Box nodes to create a Grid List Box node within a Grid List Box node, each of which you can scroll independently. For example, you can create:

In a Grid List Box node use the Layout Direction property to set how Grid List Box node arranges its items and to set the axis on which users can scroll. Set the Layout Direction to:

To nest Grid List Box nodes:

  1. Create a Grid List Box node. See Creating a Grid List Box node.
    By default the value of the Layout Direction property is Right and you can scroll the list items on the y axis. To scroll the list items on the x axis, set the Layout Direction property to Down.
  2. Create the structure for each list item of the Grid List Box node you created in the previous step.
    For example, if you want to create several nested Grid List Box nodes which contain albums, in the Prefabs create a Stack Layout 2D node, and inside it create a Text Block 2D node.
    You use the Stack Layout 2D node to position each nested Grid List Box and the album category title, and the Text Block 2D node to show the category title. See Using the Stack Layout nodes.
  3. Create a Grid List Box node that you want to nest in the Grid List Box that you created in the first step, and set it to scroll on a different axis than its parent Grid List Box node. If you set the Layout Direction property to Right for the parent Grid List Box node, for the nested Grid List Box node set that property to Down to scroll that Grid List Box on the x axis.
    For example, if you created a Stack Layout 2D prefab in the previous step, in that Stack Layout 2D create a Grid List Box node, and drag to the Project to the Grid List Box node several instances of that prefab.
  4. Add items to each nested Grid List Box node.
    For example, to create a vertically scrollable Grid List Box which contains horizontally scrollable Grid List Box of albums, in the Prefabs create an Image node you use to represent each album, and drag to each nested Grid List Box several instances of that prefab.
    You can add items to a Grid List Box using a data source. See Using a data source.

Binding to properties outside of a Grid List Box node

Use an alias when you want to bind a property of a list box item to a property of a node outside of the list box.

For example, if you have a Grid List Box 3D or a Trajectory List Box 3D node with a Text Block 3D node item and want to set the Text property value of the Text Block 3D node to a value of an Empty Node 3D node property that is not in the list box:

  1. In the Project press Alt and right-click the nodes that contain the property to which you want to bind and select Alias. See Using aliases.
    For example, create an alias for the Empty Node 3D node.
  2. In the Dictionaries make sure that the aliases you created are in the resource dictionary that the list box node can access.
    For example, place all aliases to the resource dictionary of the Screen node, or create a resource dictionary in the list box node and place the aliases to that resource dictionary. See Using resource dictionaries.
  3. Create the binding:
    1. In the Project select the node inside the list box node from which you want to bind to a node outside of the list box node.
    2. In the Properties add the Bindings property and create the binding using the alias to bind to the property in a node outside of the list box node.
      For example, in the Text Block 3D node create a binding to the Empty Node 3D node using the alias you created in the first step. See Bindings expressions reference.
      For example, use this binding expression: 
      {#Empty Node 3D/TextBlockConcept.Text}

      The Text property in the Text Block 3D node gets the value of the Text property from the Empty Node 3D node.
    3. Click Save.

Navigating to Page nodes from a Grid List Box node

Use an alias when you want to navigate to a Page node from a node that is inside a list box node. For example, if you use a Grid List Box or a Trajectory List Box 3D node to create an address book and want to show the content of an address book entry in a Page node.

To navigate to Page nodes from a list box node:

  1. In the Project press Alt and right-click each Page node to which you want to navigate to and select Alias.
    Kanzi Studio creates an alias that points to the node from which you created it, and places the alias to the nearest resource dictionary.
  2. In the Dictionaries make sure that the aliases you created are in the resource dictionary that the list box node can access.
    For example, place all aliases to the resource dictionary of the Screen node, or create a resource dictionary in the list box node and place the aliases to that resource dictionary. See Using resource dictionaries.
  3. Add and set the Navigate to Page action:
    1. In the Project in the list box node select the node that contains the trigger you want to use to navigate to one of the Page nodes for which you created the alias in the first step.
    2. In the Node Components > Triggers section in the trigger you want to use to navigate to the Page node add the Navigate to Page action.
    3. In the Navigate to Page settings window set the Item property to the alias of the Page node to which you want to navigate and click Save.
      All aliases start with a # sign.

In the Preview when you click the node that contains the Navigate to Page action, you activate the Page node selected in the action.

Reacting when the user interacts with a Grid List Box node

Use the List Box triggers to react when the user interacts with a Grid List Box node. For example, you can set the appearance of a Grid List Box node when the user scrolls that node.

You can use these List Box triggers with the Grid List Box nodes:

To use the List Box triggers with a Grid List Box node:

  1. Create a Grid List Box node and add items to it. See Creating a Grid List Box node.
    For example, create a Grid List Box 2D node.
  2. Define the behavior that you want to set with the List Box triggers.
    For example, create a state manager where you define the states which set the appearance of the Grid List Box 2D node when the List Box: Scroll Started and List Box: Scroll Finished triggers are set off. See Creating a state manager.
  3. Add and configure a List Box trigger:
    1. In the Project select the List Box node to which you want to add the trigger, and in the Node Components > Triggers section add one of the List Box triggers.
      For example, in the Project select the Grid List Box node which you created in the beginning of this procedure and in the Node Components add the List Box: Scroll Started trigger.
    2. In the trigger you created in the previous step, in the Add dropdown menu select an action and configure it.
      For example, select the Go to State action, and in the action settings set:
      • Item to the Grid List Box node you created in the beginning of this procedure
      • State to the state which sets the appearance of the Grid List Box node when the List Box: Scroll Started trigger is set off
  4. Repeat the previous step to add and configure more List Box triggers.
    For example, add the List Box: Scroll Finished trigger. In the Go to State action of the trigger set State to the state which sets the appearance of the node when that trigger is set off.

In the Preview when you scroll the Grid List Box node you created, the triggers you added are set off.

Setting the appearance of a Grid List Box 2D node

To set the appearance of 2D nodes:

Using the Grid List Box 3D node in the API

To create a Grid List Box 3D: 

// Create a Grid List Box 3D named MyListBox.
GridListBox3DSharedPtr gridListBox = GridListBox3D::create(domain, "MyListBox");

To configure the grid area: 

// Make each grid cell be a 1x1x1 cube.
gridListBox->setCellWidth(1.0f);
gridListBox->setCellHeight(1.0f);
gridListBox->setDepth(1.0f);
// Make the grid contain three rows that are filled column by column.
gridListBox->setHeight(3.0f);
gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
// Make the grid contain 10 columns. Items that are dragged beyond these columns are made invisible.
gridListBox->setWidth(10.0f);
// Change the resting position when the list is scrolled to the beginning or end, so that items are not right at the grid edge.
gridListBox->setItemAreaBegin(0.2f);
gridListBox->setItemAreaEnd(0.8f);

To add items to the list box: 

// Create cube meshes and add them as items of the list box.
// Items on the grid appear in the order you add them to the list.
Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
gridListBox->addItem(item1);
gridListBox->addItem(item2);
gridListBox->addItem(item3);
gridListBox->addItem(item4);
gridListBox->addItem(item5);

For details, see the GridListBox3D class in the API reference.

Using the Grid List Box 2D node in the API

To create a Grid List Box 2D: 

// Create a Grid List Box 2D named MyListBox.
GridListBox2DSharedPtr gridListBox = GridListBox2D::create(domain, "MyListBox");

To configure the grid area: 

// Make each grid cell be a 100x100 square.
gridListBox->setCellWidth(100.0f);
gridListBox->setCellHeight(100.0f);
// Make the grid contain three rows that are filled column by column.
gridListBox->setHeight(300.0f);
gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
// Make the grid contain 10 columns. Items that are dragged beyond these columns are made invisible.
gridListBox->setWidth(1000.0f);
// Change the resting position when the list is scrolled to the beginning or end, so that items are not right at the grid edge.
gridListBox->setItemAreaBegin(0.2f);
gridListBox->setItemAreaEnd(0.8f);

To add items to the list box: 

// Create images and add them as items of the list box.
// Items on the grid appear in the order you add them to the list.
for (int i = 0; i < 5; ++i)
{
    Image2DSharedPtr item = Image2D::create(domain, "item" + to_string(i));
    item->setImage(item->acquireResource<Texture>(ResourceID("DefaultTexture")));
    // Make the images shrink to the cell size.
    item->setHorizontalAlignment(Node::HorizontalAlignmentStretch);
    item->setVerticalAlignment(Node::VerticalAlignmentStretch);
    gridListBox->addItem(item);
}

For details, see the GridListBox2D class in the API reference.

Grid List Box property types and messages

For lists of the available property types and messages for the Grid List Box nodes, see Grid list box 2D and Grid list box 3D.

See also

Tutorial: Create a contacts list with a Grid List Box

Using the Trajectory List Box 3D node

Using the Grid Layout nodes

Using the List Box Item Container prefabs

Enabling the click gesture for a node using Kanzi Studio

Open topic with navigation